Charge an agreement

The charge agreement step is used to charge the customer's credit or debit card based on the specified agreement.

You can do this step as many times as you want to charge the agreement.

The following diagram describes a typical charge agreement flow using the Merchant API, where the transaction is initiated by the merchant(MIT).

The following diagram describes a charge agreement flow using the Merchant API, where the transaction is initiated by the customer(CIT). This kind of transactions involves the customer interaction for authentication.

You can charge an agreement using one of the following methods:

/chargeSubscription

This method captures the charge agreement payment.

To capture several payments, you can call the method multiple times.

For more details about the chargeSubscription method, please see chargeSubscription page.

  curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/chargeSubscription \
  --header 'Authorization: Basic auth' \
  --data 'agreement[id]'=15 \
  --data `agreement[unscheduled_type]`=noShow \
  --data amount=50 \

/reserveSubscriptionCharge + /captureReservation

This method preauthorise the charge agreement payment. Use it in combination with /captureReservation in order to capture the payment.

To preauthorise and capture several payments, you can call the method multiple times.

For more details about the reserveSubscriptionCharge method, please see reserveSubscriptionCharge page.

For more details about the capture method, please see captureReservation page.

reserveSubscriptionCharge request

  curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/reserveSubscriptionCharge \
  --header 'Authorization: Basic auth' \
  --data 'agreement[id]'=15 \
  --data `agreement[unscheduled_type]`=noShow \
  --data amount=50 \

captureReservation request

  curl --request POST \
  --url https://<YourShopName>.altapaysecure.com/merchant/API/captureReservation \
  --header 'Authorization: Basic auth' \
  --data transaction_id=12345 \
  --data amount=20 \

The transaction_id is the public id of the setup agreement transaction.

The transaction_id parameter becomes agreement[id]. If you have used the transaction_id parameter for charging the existing subscriptions(hereinafter referred to as agreement), you can still use it for a while, but we encourage you to switch to agreement[id].

The value of the agreement[id] will be the value of the transaction_id stored at the setup agreement step.

The following table describes the required parameters when charge an agreement

The following list does not represent the complete list of the parameters used when charge an agreement. For the entire list of the parameters, please check the parameters list of the charge agreement method used.

Select from the drop-down list to see the parameters relevant for that method/acquirer:

Parameter

Description

Type

Mandatory

agreement[id] / transaction_id

This is the id of the setup agreement payment.

The transaction_id parameter is deprecated but still can be used as an alias for agreement[id] for a while, but we encourage you to use agreement[id]

[0-9a-f]{1,32}

Yes

agreement[unscheduled_type]

This is the type of the unscheduled agreement.

Below you can find more details about the agreement[unscheduled_type] parameter and the possible values.

String

Yes, when charge an unscheduled agreement.

agreement[retry_days]

The number of days when the provider will retry the charge.

This parameter is used only by recurring charges, called by MobilePay "Subscription Payment".

integer

No. Default value: 2

orderLines

The individual line items of the order. This is mandatory for some providers, and recommended for a good customer experience.

See details here

One order line with the following parameters is required for wallet integration in order to ensure a good customer experience.

Value	Description	Type
description	Description of the charge agreement.	String (255)

Item, UnitPrice and quantity parameters might be required for this order line, but that parameters are not relevant to the Create agreement request.

Array

No. Create agreement order lines will be used as a default in case order lines not provided.

Unscheduled type

When the charged agreement has agreement[type]=unscheduled, the agreement[unscheduled_type] parameter is mandatory.

In the below table are described the possible values to be set for the agreement[unscheduled_type] parameter.

Unscheduled type	Description	Initiation Type
incremental	An incremental authorisation is typically found in hotel and car rental environments, where the cardholder has agreed to pay for any service incurred during the duration of the contract. A common scenario is additional services charged to the contract, such as extending a stay in a hotel. For the incremental authorisation, the cardholder authentication is not required.	MIT
resubmission	This is an event that occurs when the original purchase occurred but the Merchant was not able to get authorisation at the time the goods or the services were provided. For the resubmission authorisation, the cardholder authentication is not required.	MIT
delayedCharges	A delayed charge is typically used in hotel, cruise lines and vehicle rental environments to perform a supplemental account charge after original services are rendered. For the delayed charge authorisation, the cardholder authentication is not required.	MIT
reauthorisation	A reauthorisation is a purchase made after the original purchase. A common scenario is delayed/split shipments. For the reauthorisation, the cardholder authentication is not required.	MIT
noShow	A no-show is a transaction where the merchant are enabled to charge for services which the cardholder entered into an agreement to purchase, but the cardholder did not meet the terms of the agreement. For the no-show authorisations, the cardholder authentication is not required.	MIT
charge	A transaction using a Stored Credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date. This includes account top-ups triggered by balance thresholds. For the charge authorisations, the Strong Customer Authentication takes place.	CIT

When the Charged agreement transaction is a Customer Initiated Transaction(CIT) or the transaction must be authenticated

Normally, when doing this step, the agreement will be charged right away, but for the cases when the transaction is CIT or the transaction was Soft Declined, and it should to be authenticated, you will receive a redirect response where the customer should be redirected in order to authenticate the payment.

Below is an example of a redirect response

Redirect response:

<?xml version="1.0" encoding="utf-8" ?>
<APIResponse version="20170228">
    <Header>
        <Date>2021-11-16T08:19:10+00:00</Date>
        <Path>API/reserveSubscriptionCharge</Path>
        <ErrorCode>0</ErrorCode>
        <ErrorMessage/>
    </Header>
    <Body>
        <Result>Redirect</Result>
        <RedirectResponse>
          <Url>https://testgateway.altapaysecure.com/eCommerce/API/3ds/737f04f7-2eeb-46c6-b003-a1a623cd2443/input?callback=https%3A%2F%2Ftestgateway.altapaysecure.com%2FeCommerce%2FAPI%2FValidatePaymentAuthenticationCollect3DSDataCallback%2Fdf176859-e715-4104-b101-6841ce14a042</Url>
          <Method>GET</Method>
          <Data/>
        </RedirectResponse>
    </Body>
</APIResponse>

For more details about the redirect response, please see redirect response page.